/**
 * Copyright 2010 Tristan Slominski
 *
 * Licensed under the MIT License (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.opensource.org/licenses/mit-license.php
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.mindash.handlebars.client.services.utils;

import java.util.Map;

/**
 * @author Tristan Slominski
 * 
 */
public interface PlaceServiceUtils {

  /**
   * Retrieves place name from the history token (which could contain a query
   * string).
   * 
   * @param historyToken the history token
   * @return the place name, ie: string between '#' and '?'
   */
  public String getPlaceName(String historyToken);

  /**
   * <p>
   * Parses the url parameters in the history token, as well as the params in
   * the query string before the # marking the history token
   * </p>
   * <p>
   * For example:
   * <code>http://unecloud.com?param1=beforeToken#historyToken?param2=afterToken</code>
   * , will return <code>param1</code> and <code>param2</code> in the map.
   * </p>
   * 
   * 
   * @param historyToken the history token
   * @return the hash map of found parameters
   */
  public Map<String, String> parseUrlParams(String historyToken);

  /**
   * <p>
   * Goes through the params and assembles them into a string with a lead '?'.
   * This method handles the URL encoding of param names and values.
   * </p>
   * <p>
   * For example: <code>param1</code> with value <code>value1</code> and
   * <code>param2</code> with value <code>value2</code> will result in
   * <code>"?param1=value1&param2=value2"</code>
   * </p>
   * 
   * @param map the params to convert
   * @return the string with leading "?"
   */
  public String paramsToUrlString(Map<String, String> map);

}
